第 2 章 R Markdown 的基础知识

本节首先介绍运行 R Markdown 的软件配置，并带领读者编译第一个 R Markdown 源文档，生成 HTML 和 PDF 两种格式。随后探讨了 R Markdown 的编译机制。最后介绍了各类通用的文档元素。

本书推荐读者使用 RStudio 编辑器作为开发环境。RStudio 编辑器是 R 社区中最流行的编辑器之一，并集成了许多便利 R Markdown 文档书写的功能，例如简单的图形化按钮，在线预览，视觉编辑器等。RStudio 编辑器的免费开源版本可从 https://www.rstudio.com/products/rstudio/ 下载，英文名称为 RStudio Desktop Open Source Edition。

安装完成后，打开 RStudio 编辑器，基本界面如图 2.1 所示。

图 2.1: RStudio 编辑器的基本界面

RStudio 编辑器默认将工作区域分为三个面板，其中左侧为为 R 的控制台 (console)，用于交互式的代码输入和输出；中间为编辑器 (editor)。右上包括当前 R 进程的环境，历史和连接等信息，右下包括文件浏览器，图和帮助文档等。读者可以通过菜单栏中的 Tools -> Global Options -> Pane Layout 调整面板的排列。

R Markdown 文档的编译依赖于同名的 rmarkdown R 包，在控制台中输入如下命令安装：4

安装完成后，在 RStudio 的菜单栏中选择 File -> New File -> R Markdown，点击 OK 后， 即可创建一个新的 R Markdown 文档模版，如图 2.2 所示。

图 2.2: 在 RStudio 中创建 R Markdown 文档

随后，RStudio 创建了一个 untitled.Rmd 文件，如图 2.3 所示。

图 2.3: RStudio 中的 R Markdown 编辑器

.Rmd 文件是 R Markdown 的源文档，是撰写 R Markdown 文档的主要工作区域，一个文档的内容、格式、标题等都在这里定义，本书后续章节对文本和代码的编辑均是围绕类似这样的源文档展开的。

为了验证 rmarkdown 包及 RStudio 配置成功，可以在 RStudio 中打开 untitled.Rmd 文件，然后点击右上角的 Knit 按钮，即可在 RStudio 中看到编译后的文档，如图 2.4 所示。

图 2.4: 源文档上方的编译按钮

图 2.5: untitled.Rmd 文件输出的 HTML 文档

untitled.html 文件是 untitled.Rmd 源文档的编译结果，称为输出文档。HTML 是 R Markdown 文档的默认输出格式，后续章节介绍了其他输出格式的使用方法。

除了 RStudio 中的 Knit 按钮，读者还可以在 RStudio 的控制台中输入如下命令，对 R Markdown 文档进行编译：

rmarkdown::render() 函数是编译 R Markdown 文档的重要工具，也是 Knit 按钮背后调用的函数。读者可以为 render() 提供各类参数自定义各项输出设置，将在后续章节中介绍。

要想使用 R Markdown 输出 PDF 格式的文档，必须事先安装 LaTeX。LaTeX 有很多发行版，如 MiKTex，MacTeX， TeX Live 等，建议 R Markdown 的用户使用 TinyTeX。它是一个瘦身版的 TeX Live，去掉了 TeX Live 中对普通用户毫无用处的源代码和文档，可以通过 tinytex (Xie 2022d) R 包安装。

图 2.6: TinyTex 是一个瘦身版的 TeX Live

要安装 TinyTeX，只需要在 R 语言终端输入两条命令即可5。

如果 TinyTeX 下载速度慢，或在 R 里面下载不完整，那么可以用浏览器或其它下载工具直接下载：https://github.com/yihui/tinytex-releases/releases 然后把下载的文件路径传给安装函数，比如：

运行完毕后，可以尝试编译 PDF 输出文档以验证 TinyTex 安装成功。以先前的 untitled.Rmd 为例，将文件的头部替换为：

随后点击 Knit 按钮，生成的 PDF 输出文档如图 2.7 所示。

图 2.7: untitled.Rmd 生成的 PDF 文档

从 rmarkdown 1.9 版本开始，输出 PDF 文档时会调用 TinyTeX，进而使用 LaTeX 包。因此，对 R Markdown 用户来说，编译 PDF 时出错的最常见原因是缺失某些 LaTeX 包。

LaTeX 包（也被称为 “package”）是 LaTeX 的组件，数目非常多，可以用来扩展 LaTeX 的功能。tinytex::install_tinytex() 默认只安装了必须的一些组件，在实际使用过程中经常会出现缺少组件的错误。

如果知道包的名称，那么可以直接使用下面的命令安装。这里值得注意的是，国内用户通常需要额外设定 LaTeX 软件仓库的位置。下面的例子使用了清华大学的 TeX Live 镜像。

如果不知道包的名称也没有关系，tinytex 也提供了相应的函数来帮助用户从报错信息中找到解决方法。tinytex::parse_install() 提供两种方法，第一种是通过准确的错误提示，第二种是通过分析 log 日志文件。如果 log 文件过长或者找不到具体提示信息，还可以使用第二种办法。

了解 Git 和 Github 的使用可以帮助 R Markdown 用户分享代码和输出结果，并且可以方便地与他人协作。

Git 是一个分布式版本控制软件，最初由 Linus Torvalds 开发6，于 2005 年以 GPL 协议发布。Git 软件可以在其官方网站下载（https://git-scm.com/downloads）。为了与 Git 配合使用，通常还需要注册一个支持 Git 软件仓库托管的配套网站，比较流行网站服务包括 GitHub（https://github.com），Gitee（https://gitee.com/）等。在这里以 GitHub 为例进行说明。

图 2.8: 使用 Git 和 GitHub 可以提高团队协作的效率

Windows 系统下 7，安装完 Git 客户端之后，鼠标右键菜单中会多出来两个命令：“Git GUI Here”和”Git Bash Here”。前者打开一个图形界面，后者打开一个终端，通过这两个命令都可以进入 Git。

首先需要配置 Git 的用户信息，下面是终端命令：

为了能够使用 GitHub 提供的服务，需要先注册一个账号（https://github.com/signup）。

Git 常用的命令有下面几个：

git init sample

在当前目录新建一个”sample”目录，在目录中启用 Git 版本控制系统。

git clone https://github.com/cosname/rmarkdown-guide.git

从 GitHub 克隆一个软件仓库到当前目录。这将在当前目录新建一个”rmarkdown-guide”文件夹，其中包含所有文件和版本历史。

git status

显示当前 Git 仓库的状态。如果有修改，新建，删除等操作，将会自动列举出来。

git add newfile.Rmd

newfile.Rmd 是一个新建的文件，其中有一些新增的代码。该命令将其加入 Git 追踪的文件清单中。

git commit 或者 git commit -a

这个命令将执行一次 Commit 操作，系统会打开默认的文本编辑器，以填写本次 Commit 操作涉及的工作内容。

git push

将本地仓库的修改推送到远程仓库中去。要执行该命令，本地仓库需要关联一个远程仓库，并且用户对该远程仓库具有修改权限（使用 git remote -v 查看本地仓库关联的远程仓库地址）。

git pull

将本地仓库的内容与远程仓库同步（这是远程仓库的文件比本地仓库的文件版本新）。

SSH 密钥是成对的，包括公钥和私钥；公钥登记到 GitHub 网站，私钥存储在本地计算机（私有）。密钥在本地生成。点击鼠标右键，选择”Git Bash Here”，输入下列命令将生成一对 SSH 密钥。 默认情况下，私钥保存在”~/.ssh/id_rsa“文件中，公钥保存在”~/.ssh/id_rsa.pub”文件中 （在 Windows 系统中的 Git bash 终端下，~ 代表用户的家目录）。

复制这个公钥的全部内容，进入”GitHub - Setting - SSH and GPG keys”，选择”New SSH key”，将公钥粘贴进去，点击”Add SSH key”，即可完成公钥添加。

这样，以后就调用 “Git Bash Here” 时，便会自动提供私钥认证，不需要输入用户名和密码了。

在 GitHub 网站中，通常主要进行下列操作：

创建一个新的软件仓库；

点击 GitHub 右上角的 “+”，选择 “Create a new repository”，按照提示操作即可。这步操作其实相当于在 GitHub 服务器上新建了一个目录。目录名称是 Repository Name。目录的路径就是 /。对应的网址（绝对路径）是 https://github.com//。对应的 Git 地址是 git://[email protected]//.git。对应的 SSH 地址是 ssh://[email protected]//.git。

从其他用户的软件仓库中新建一个分支，即 Fork；

在 GitHub 项目网页中，点击”Fork”即可。

为其他用户的软件仓库中贡献代码，即 Pull Request；

因为自己不具备其他用户拥有的软件仓库的编辑权限，所以无法直接通过 push 的方法提交修改。在这种情况下，用户可以首先在 GitHub 上 Fork 其他用户的软件仓库，并在自己的 Fork 中做相应修改后，通过 Pull Request 的方法提交给其他用户，经过管理员审核后，即可合并到对方的软件仓库中去。这也是团队协作共同维护一个项目时的常规操作。

第 7.2.8 节还将介绍使用 GitHub Actions 实现自动化完成持续性集成（Continuous Integration，CI）的功能。

第 2.2 节中，读者创建了 untitled.Rmd 源文件，这是 rmarkdown 自带的一个文档模版，目前读者不需要修改其中的内容，untitled.Rmd 原内容如下：

这个文件中包含了 R Markdown 文档中的三个基本元素，从上到下包括：

元数据用 YAML 语法以 key: value 的形式指定了源文档的各类输出设置，不涉及具体的正文内容。这里 untitled.Rmd 的元数据做了两项设置，title: "Untitled" 设定了文档标题，而 output: html_document 设定了输出格式为 HTML。

这是一个 R 代码块，因为```{ 后是 r，读者还可以将其替换为 ```{python， ```{bash 等以指定代码块的语言类型。语言名称的后面还可以附上代码块选项。代码块选项与代码块的关系就如同 YAML 元数据之于整个文档一样，用于指定该代码块的运行和输出设置。这里，setup 是代码块的标签，include=FALSE 指定了这个代码块的内容不会显示在输出中，即隐藏 knitr::opts_chunk$set(echo = TRUE) 这一行，第 2.7 节解释了它的含义。

这段内容使用了 Markdown 语法。Markdown 语法提供了一系列简单的标记符号，如 #，*，- 等，它们可以在输出文档中生成标题、列表、图片和脚注等常见元素，满足简单的样式需求。使用 Markdown 既可以让作者免于复杂的排版之苦，也提供了一种格式标记的统一中介。本书的第 2.6 节详细介绍了 Markdown 语法。简而言之，R Markdown 在遇到这些符号时会将相关的文本转换成对应的格式。这里 ## R Markdown 是一个二级标题，**Knit** 是一个加粗的文本， 是一个链接。

这段 Markdown 文本下面是另外一个 R 代码块：

这个 R 代码块的标签是 cars，内容是 summary(cars)。编译过程中，R Markdown 会运行这段代码内容，并将生成的结果插入到该段代码的下方，这个结果可以是文本，也可以是图片，表格等，例如第三个代码块 plot(pressure) 就生成了图片。

untitle.Rmd 的剩余内容是类似的 Markdown 文本和代码块。

点击 Knit 按钮或调用 rmarkdown::render() 函数后，R 会启动一个新的进程，将源文档转换为输出文档。 之前提到过，Knit 按钮本质上就是对 rmarkdown 包中 render() 函数的封装。因此，理解 R Markdown 的编译过程就是理解 render() 调用了什么方法和工具完成了怎样的文档转换。

首先，render() 函数会读取 YAML 元数据，并根据它们设置的选项来调整输出文档的配置。

YAML 元数据读取完毕后，进入文档的正文部分。R Markdown 首先提取正文中的所有代码块，按顺序运行其中的代码，将运行结果插入到代码块的下方。代码的执行过程在底层由 knitr (Xie 2022c) 包控制，它将代码的运行结果置于合适的位置。之前笼统说的 “R Markdown 运行代码” 实质上就是 knitr 的工作。这一步结束后，knitr 生成了临时性的 .md 文件。包含了 Markdown 文本和代码运行结果。例如，untitled.Rmd 被转换为 untitled.md，内容为：

这里的 .md 文件是一个纯文本文件，在内容上已经和最后的输出文档一致，但还欠缺最后的格式转换。接下来，R Markdown 会调用 Pandoc 软件负责下一步的转换。Pandoc 是一个开源的命令行程序，可以完成多种文档格式之间的互相转换，已经随 RStudio 下载安装好。这里，Pandoc 将 .md 文件 转换为 YAML 头部中 output 对应的输出格式。Pandoc 还读取了其他 YAML 头部中的设定，一些被插入文档内容 (如 title)，另一些选项则作为命令行参数，对转换过程做特定的控制。用以下代码验证 Pandoc 的安装版本：

作为总结，对于 HTML 格式，rmarkdown::render = knitr + Pandoc。 PDF 输出格式还有额外的一步： tinytex 包或其他 LaTeX 发行版编译 Pandoc 生成的 .tex 文件，生成 PDF 文档。

实际写作中，R Markdown 用户几乎不需要直接与 knitr 或 Pandoc 打交道，大部分配置可以通过 YAML 元数据完成，但理解它们在 R Markdown 编译中的角色有利于在编译失败时更好地排错，同时为掌握更进阶的排版技巧打好基础。

图 2.9 概括了 R Markdown 完成以上工作的流程。

图 2.9: R Markdown 的编译过程 https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-process.html

了解完 R Markdown 的编译过程后，下面三节深入介绍了 R Markdown 源文档中的三种元素：YAML 头部，Markdown 文本和代码块。

YAML 元数据中的每一个域 (field) 都定义了输出的一个方面，其中最重要的一个域是 output 所指定的输出格式，output 选项的值可以是 html_document、pdf_document、word_document 等，这些值对应了不同的输出格式，实质上都是 rmarkdown 包中的函数，例如 html_document 对应的函数是 rmarkdown::html_document()。下面是所有 rmarkdown 包中定义的输出格式：

作者还可以进一步设置某个输出格式的二级选项，例如：

可用的二级选项可以在对应的输出函数中找到，使用 ?rmarkdown::html_document 可以查看 html_document() 的文档，其中的每一个参数都是可在 YAML 头部中设置的二级选项。

output 选项的值还可以是一个列表，这样就可以同时生成多个文档。例如，下面的代码会同时生成 PDF、Word 和 HTML 文档。

上面的文档有三种可选的输出格式，html_document，pdf_document 和 tufte_html。

在 html_document 格式中，toc: true 指定自动生成目录, toc_float: true 设置目录的显示方式为浮动侧边栏 (默认标题会固定在正式文字内容之前), code_folding: hide 可以折叠所有代码块，但读者可以在每个代码块右上角的选项卡展开内容，这是一个 HTML 输出格式特有的选项。9

pdf_document 格式同样设置了生成目录，number_sections: true 自动生成章节编号，keep_tex: true 保留 Pandoc 生成的 .tex 文件。latex_engine: xelatex 设置编译引擎为 XeLaTeX (默认为 pdflatex), 引擎设置对正确显示中文字体非常重要。

tufte::tufte_handout 是 rmarkdown 包之外的一个扩展输出格式：用户可以根据自己的需求定制输出格式，不限于 rmarkdown 包内置的格式。tufte::tufte_handout 是 tufte 包中的一个函数，模仿了统计学家 Edward Tufte 以及物理学家费曼的教科书的风格。举一反三，如果需要使用 foo 包中的输出格式 bar，它定义在 bar_document 中，那么 output 应该设置为 output: foo::bar_document，这里的 default 关键字表示使用默认的二级设置。使用多个输出格式时，没有二级选项的输出格式需要使用 default。下面的 YAML 元数据是不合法的：

除了 output 之外，常见的 YAML 域包括 title (标题)、author (作者)、date (日期)、subtitle (副标题) 和 abstract (摘要) 等，它们的用法很简单，在 : 指定对应的值即可，参见下面的源文档：

这里，> 可以让多行的字符串在输出中按一行输出，起到相反作用的是 | 号，它保留字符串中的换行符。fontsize, papersize, geometry, biblio-title, bibliography,link-citations, documentclass 等是生成 PDF 文档的通用选项，所以它们不是写在某个输出格式下面 (pdf_document 只是能生成 PDF 文档的格式之一)，而是顶层的元数据。类似这样的选项还有很多，读者可以在需要时自行搜索他们的用法。非 PDF 输出格式则会无视它们。

输出结果如 2.10 所示。

图 2.10: YAML 元数据对应的 PDF 输出

ymlthis 包提供了一个在 R Markdown 中插入 YAML 数据的图形化界面，可以在 RStudio 菜单栏的 Tools -> Addins -> Browse Addins 中启动，如图 2.11 所示。

图 2.11: ymlthis 包提供图形化输入 YAML 元数据的插件

Markdown 标记语言由 John Gruber 于 2004 年创建，以易读，可移植，跨平台等优势成为最受欢迎的技术写作工具之一。借助 Markdown，作者可以在纯文本文档中用特殊的标记符号表示格式，例如用井号 # 表示标题，用 * 星号表示加粗等。这样的统一中介使作者不必逐个为特定输出格式设置排版方案。

Markdown 提供了很多简单的段内格式化 (inline formatting) 方法，一些基础的格式列举如下：

粗体: 前后各添加两个星号 **。如 **加粗** 在输出文档中变为 加粗

斜体：前后各添加一个星号 *。如 *斜体* 变为 斜体

代码样式: 前后各添加一个反引号 `。如 `代码` 变为 代码。如果内容本身有反引号，可以在两边添加同等数量的反引号，如 ``x`` 变为 `x`

用 插入一个可点击的链接，如 显示为 https://example.com。带文字的超链接格式为：

例如，[R Markdown 权威指南](https://bookdown.org/yihui/rmarkdown/) 显示为 R Markdown 权威指南。

要在 Markdown 中换行，需在上一段的末尾添加两个或以上空格 (仅一个回车键不能换行)。例如：

生成:

R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS.

更简单的办法是在两行间添加一个空行：

段落级别 (block-level) 的格式用于创建具有特定格式的整个段落。除了常规文本外，常见的段落元素包括标题，列表，块引用，代码块等。

用引号 # 创建不同层级的标题，引号的数量表示标题的层级。如 # 一级标题 创建一级标题，## 二级标题 创建二级标题，### 三级标题 创建三级标题等。注意在井号和标题文字之间要保留一个空格。如果 YAML 元数据中的 number_sections 选项设置为 true，则章节会自动编号。如果想为某些章节取消标号，可以在标题后添加 {-} 或 {.unnumbered}, 例子如下：

读者还需注意，对没有编号的标题使用交叉引用时，只能用 Markdown 链接 [文字](#label), 而不能用 \@ref(label)，后者是基于编号的引用。

在列表项之前添加减号 - 或星号 * 以创建列表，同样注意文字前的空格。缩进一个或多个列表项可创建嵌套列表。

显示为：

还可以用数字编号创建有序列表，与上面的无序列表结合使用，如：

显示为

用大于号 > 创建一个块引用 (blockquote)

在输出文档中渲染为：

生活是很枯燥的。我的一生就是力求不要在平庸中虚度光阴。这些小小的案件让我遂了心愿。

注意: 这里的代码块只是有特殊格式的文字块，不同于可运行的代码，我们也无法在输出文档中得到它们的运行结果。

在文字前后各添加三个反引号 ``` 可以创建一个代码块，如：

图 2.12 展示了渲染为 PDF 后的效果。

图 2.12: Markdown 常见元素的显示效果

Markdown 中的特殊字符包括 #, *, -, ` 等，通常它们代表了特定的排版格式，当需要按字面意输出这些特殊字符时，可以在前面使用转义符 \。

值得一提的是，虽然 Markdown 本身是一种统一的标准，随着时间推移独立开发者们逐渐添加了不同的功能扩展，一些组织和公司在此基础上加以规范化，形成了不同的 Markdown 变体 (flavor)。R Markdown 中使用的是 Pandoc 式的 Markdown，即 Pandoc 支持的 Markdown 语法。其他平台支持的常见变体包括 ExtraMark Markdown 和 Github Markdown 等。如果某个特定语法在 R Markdown 中无法正常显示，很可能是 Pandoc Markdown 不支持这个语法。

一些 Markdown 编辑器提供了即时预览功能，方便读者进行交互性的练习。图 2.13 是一个在线编辑器的例子。

图 2.13: 支持实时预览的 Markdown 编辑器 https://dillinger.io/

在 R Markdown 中，R 代码有两种使用方式: 代码块和行内代码。

R 代码块以 ```{r} 开始，``` 结束，作者可以在源文档中插入任意个代码块 11。与 YAML 元数据控制文档的整体设置类似，可以用代码块选项 (chunk options) 来控制单个代码块的运行细节。例如生成图片时，可以用 fig.width 和 fig.height 选项来控制图片的宽度和高度。

有时作者只希望展示代码的运行结果，而隐藏具体实现细节，这时可以设置代码块选项 echo = FALSE，R Markdown 会照旧运行代码，但仅在输出文档中显示运行结果。如果文档中包含很多代码块，逐个设置选项较为繁琐。这时可以用 knitr 包提供的 knitr::opts_chunk$set() 函数为所有代码块统一设置全局选项。例如，在全文档中的第一个代码块中设置：

这样，cars 及后续的代码块就会继承 knitr::opts_chunk$set() 中的选项。通常，全局选项被放置在整个文档的第一个代码块中，且设置该代码块的选项为 include=FALSE，这样，这个代码块本身就不会在文档中显示出来了 12。 如果后续的代码块需要覆盖全局选项，也可以在代码块中重新设置选项。

现在 cars 代码块的选项为 echo = TRUE, fig.wdith = 10, fig.height = 5 和 fig.align = "center"。

一些时候可能不需要单独成段的代码块，而是想在 Markdown 文本的同一段嵌入代码的运行结果，这时可以使用行内代码 (inline code)。行内代码位于一对反引号内部，以 r 开头，空格后面是 R 的表达式 13，例如下面的文本：

在输出文档中变为：

行内代码与定时任务结合使用，可以实现报告文档的自动更新。

行内代码的使用不限于正文，一个常见用法是动态更新文档的编译日期。在 YAML 元数据中可以将 date 设置为 R 表达式 Sys.Date()，这样每次编译时，R Markdown 都会将日期的值更新为当前编译的日期。

读者可以在 https://yihui.org/knitr/options/ 查看所有代码块选项，这里列出一些重要选项和它们的取值类型。第 @ref(#chunk-options) 节展示了更多例子。

eval: 是否运行该代码块

echo: 是否显示代码块内容

results：如何处理代码块和运行结果

include: 是否显示代码块和运行结果，include = FALSE 等价于 echo = FALSE 和 results = 'hide'

error：是否允许代码块包含错误代码。默认情况下，只要一个代码块运行失败，整个 R Markdown 文档就无法编译成功。当想要展示错误的代码写法时，可以用 error = TRUE 或 eval = FALSE

message 和 warning： 是否显示代码块可能输出的提示和警告

collapse: 为 true 时，在输出文档中将代码块和运行结果放置在同一个块级元素中

fig.width 和 fig.height: 调整代码块生成图形时图形设备 (graphical device) 的大小。 kntir 首先通过图形设备将图片存储为文件 (例如 png, jpg)，随后在输出文档中引用这些文件。默认情况下 fig.width = 7, fig.height = 5。两个类似的选项是 out.width 和 out.height, 通常取值为百分比，表示图片占据一页的比例。例如, out.height = '80%' 表示图片占据容器高度的 80%。

fig.cap: 图片的标题

fig.align: 图片的对齐方式，有三种取值

cache: 是否缓存代码块的运行结果。如果代码块涉及复杂的计算，cache = TRUE 可以让 knitr 把运行结果保存为 .rds 文件，并在下次编译时略过计算过程，直接读取 .rds 节省时间。只有代码块的内容发生变化时，knitr 才会重新计算并更新 .rds 文件。有时 knitr 的缓存机制会让人难以预测代码是否重新运行，只推荐必要时使用。

knitr 1.35 及以后版本支持在代码块内部用 #| 符号 设置代码块选项，例如：

一些读者可能更喜欢 YAML 语法而不是用逗号分隔各选项，#| 实现了这一点：

需要注意的是，代码块内的选项优先级比常规选项更高，例如下面的代码段最终的选项为 echo = FALSE 和 collapse = FALSE

默认情况下，代码块生成的图片在输出文档中被直接插入该代码块的下方。一个重要的 knitr 选项是 fig.cap，它可以为图片添加标题。例子如下：

生成的图片如图 2.14 所示。

图 2.14: cars 数据集

当一个代码块生成多个图片时，R Markdown 会把它拆分成多个代码块，每个代码块生成一个图片，效果如下：

如果想要把多个图片放在同一个代码块中，可以使用代码块选项 fig.show = 'hold'，它告诉 R Markdown 不要拆分代码块，而是运行完全部代码后，把生成的图片依次附在下方。与 out.width 选项结合使用，可以将多个图片并排放在同一行中，效果如下：

对于非代码生成的外部图片，可以使用 Markdown 的图片语法  或 knitr 包中的函数 knitr::include_graphics() 插入图片。例子如下：

使用 include_graphics() 的好处是可以用代码块选项控制图片的细节。

第 2.6.6 节介绍了用 Markdown 语法编写表格的方法。对于 R 用户，更简单的插入表格方法是使用 knitr 包中的 kable() 函数，它接受一个数据框，返回对应的表格。与图片的 fig.cap 选项类似，作者可以用 kable() 函数中的 caption 参数控制表格的标题。例如下面的代码块：

生成的表格如表 2.1 所示。

一个常见的用例是将表格数据存入 csv 文件中，随后在 R Markdown 中读取该文件并生成表格。例如：

LaTeX 命令 \newpage 可以在文档中插入一个分页符。\newpage 的使用不局限于 PDF 输出格式，R Markdown 会自动将其转换为其他格式中的分页符，支持的格式包括 HTML、PDF、Word、ODT 等。例如：

如果只想插入一条水平的分割线而不分页，可以插入三个减号 ---。

LaTeX 命令在其他输出格式中的转换是由自定义 Pandoc 中的 Lua Filters 实现的，有兴趣的读者在 R 中查询相关文档：

YAML 元数据中的 toc: true 是所有输出格式的通用选项，用以自动生成目录，toc_depth 控制显示深度。如：

此时目录只会显示一级标题和二级标题，略过级别更低的标题。

html_document 和 bookdown::html_document2 等输出格式支持 toc_float 属性，为 true 时，目录变为侧边栏，并固定在屏幕左侧。toc_float 支持更多细节选项，包括：

collapsed (默认为 true)：是否折叠二级标题以下的标题

smooth_scroll (默认为 true)：是否在鼠标点击目录时添加平滑滚动

例子如下：

TODO：这一部分以后应当结合 Zotero 和 EndNote 等常用文献管理软件做适当扩展。

R Markdown 支持在输出文档末尾自动生成参考文献，并提供了很方便的引用格式。这项功能是通过 Pandoc 实现的，它有两种管理引用和参考文献的方式

默认情况下，Pandoc 会使用 [pandoc-citeproc](https://github.com/jgm/pandoc-citeproc) 程序按照 CSL (Citation Style Language) 语言的标准和特定的 CSL 风格文件组织参考文献和引用的格式。

读者还可以使用 natbib 包 (基于 LaTeX 的 bibtex包) 或 biblatex 包提供的格式。

作者可以用 YAML 元数据中的 citation_package 选项设置 LaTeX 中的引用包，常见的选择有 natlib 或 biblatex：

citation_package 仅限于 PDF 输出格式。其他输出格式只能依靠 pandoc-citeproc，如果需要保持 PDF 格式和其他格式的一致性，就应该始终使用 pandoc-citeproc。

设置好引用格式后，还需要知道如何把参考文献的各个条目表达为数据形式。推荐读者用 BibTeX 数据库 (BibTeX Database) 管理 R Markdown 中的参考数据。BibTeX 数据库是一种纯文本文件，一般以 bib 为后缀，其中的每一个条目格式形如：

一个条目以 @type{ 开始，type 表示该条参考的类型，可以识 article, book, manual 等。在类型之后的是引用标签，如 R-base，其他项包含参考的作者，组织，地址，日期和链接等信息。每一个条目都至少包含名称，作者和时间等信息，为了使用 .bib 文件中的条目，需要用 YAML 元数据中的 bibliography 加载一个或多个 .bib 文件：

上面的例子引入了 one.bib，another.bib，yet-another.bib 三个 .bib 文件中的参考数据，biblio-style: 'apalike' 设置参考样式为美国心理学学会期刊样式 (American Psychology Association, APA)，link-cations: true 为引用添加指向参考文献的跳转链接。

用 bibliography 引入 .bib 后，便可以在文档中引用其中包含的任意条目，语法为 @key 或 [@key]，其中 key 为该参考条目类型之后的标签。如 @R-base 生成为 R Core Team (2022)，而 [@R-base] 生成 (R Core Team 2022)。

对 PDF 输出，Pandoc 会在最后一个章节后额外生成一节放置参考文献。对其他输出格式，可以在文档的最后用行内代码自动创建一个章节存放参考文献。例如，在源文档的最后插入：

被 @key 引用的参考条目会自动出现在最后的参考文献索引中，如果想在最后添加 .bib 中的全部条目，不论是否引用，可以设置 YAML 中的 notice 属性。例如：

参考”文献”还可以包括文章使用的软件包。knitr 包提供了 write_bib 函数为 R 包生成 .bib 格式的参考条目：

不提供第一个参数时。write_bib 会导出当前进程加载的全部 R 包的引用数据，作者可以在文档末尾插入如下代码段自动化生成 R 包对应的 .bib 文件：

交叉引用 (cross-reference) 可以为读者提供锚点链接，便于他们快速浏览文档中相关部分。rmarkdown 包提供的 html_document, pdf_document 等基础格式不支持交叉引用。作者可以转而使用 bookdown (Xie 2022a) 包提供的额外格式：bookdown::html_document2 和 bookdown::pdf_document2 等。

随后，作者需要为链接跳转的锚点设置一个标签，这样引用的时候才有地放矢。R Markdown 支持交叉引用章节标题、图片、表格和公式等元素，语法略有不同。

对于标题，Pandoc 会自动为章节标题设置标签。例如 # Hello World 对应的标签为 hello-world。随后就可以用 \@ref(hello-world) 引用该标题，它会生成该章节对应的编号。对中文标题，Pandoc 可以用 # 标题 {#header} 的格式为该节添加自定义标签 header，随后用 \@ref(header) 引用该节。例如本节标题设置了 ## 交叉引用 {#cross-reference}，\@ref(cross-reference) 生成为 2.8.7。建议总是给中文标题设置一个简洁的英文标签，仅包含字母和连词符，例如：

与章节标题不同，图片和表格的标签是它们所属代码块的标签。第 2.7 节中谈到可以用 ```{r label} 或 ```{r, label = "label"} 为代码块设置标签。当该代码块的输出包含图片或表格时，这个标签就可用于交叉引用。但仅有该标签还不够，交叉引用需要元素有自己的独立环境。这一点可以通过为图片和表格设置标题做到。图片可以用 fig.cap 选项，设置表格标题的方法取决于生成的函数，例如 knitr::kable 使用 caption 参数。 随后，可以用 \@ref(fig:label) 引用图片，用 \@ref(tab:label) 引用表格。

数学公式同样支持类似的标签引用，需要使用 LaTeX 中的 equation 环境，例如下面的公式：

其中 (\#eq:mean) 是公式标签，引用格式为 \@ref(eq:mean)。

下面的例子展示了章节、图片、表格和公式的引用语法：

输出如图 2.15 所示。

图 2.15: 交叉引用图片和表格

有兴趣的读者可以查看上述生成的 .html 文件，会发现标签元素的容器有对应的 id 属性。同理，PDF 输出的 .tex 文件会插入对应的 \label{} 指令，这也是交叉引用的跳转基础。

为了方便读者快速浏览，除目录之外，作者还可以在文档的末尾插入索引。索引的生成需要使用 LaTeX 包，因此只有 PDF 输出文档才支持索引。首先，创建一个 .tex 文件引用 LaTeX 的 makeidx 包，然后在 R Markdown 文档中用 includes -> before_body 选项引入这个 .tex 文件。例如，在 preamble.tex 中写入：

作者还需要在 R Markdown 文档的末尾插入 LaTeX 命令 \printindex。随后就可以使用 \index{} 创建一个索引条目。完整的源文档如下：

生成的 PDF 文档如图 2.16 所示。

图 2.16: 在 PDF 文档中插入索引

对 HTML 输出文档，R Markdown 支持 aniamtion.hook 选项 (依赖 gifski 包) 将多个图片合并成 gif 格式的动画。

为了在 PDF 输出中支持动画，首先需要安装 LaTeX 包 animate，并设置选项 fig.show = "animate"，这样创建的动画只能用 Acrobat Reader 显示。例子如下：

HTML 输出文档支持基于 JavaScript 的交互组件。htmlwidgets R 包 (Vaidyanathan et al. 2021) 让 R 用户可以轻松实现实现对 JavaScript 库的接口。在此框架上开发的 R 包如 DT (R-DT?) (表格)，leaflet (Cheng, Karambelkar, and Xie 2022) (地图) 和 ，dygraphs (Vanderkam et al. 2018) (时间序列图) 为 HTML 输出格式提供了丰富的交互组件。读者可以在 https://www.htmlwidgets.org 了解更多使用和开发 HTML 组件的更多细节。图 2.17 是一个使用 leaflet 包插入交互地图的例子。

图 2.17: 用 leaflet 包插入交互地图

对于非 HTML 输出格式，R Markdown 会用 webshot (Chang 2022) 包将组件截取为静态图片后插入输出文档中。

可以在 HTML 输出中插入音视频等多媒体文件，如果读者使用的提供商支持在网页端界面，则只需要复制该段插入代码，例如下面的代码块插入了哔哩哔哩的视频：

这里的 =html 是针对 HTML 格式的特殊代码环境，代表其中的内容为原生 HTML 代码，直接插入生成的 HTML 文件中，效果如下：

如果音视频文件托管于其他服务器上，则可使用原生的 HTML audio 和 video 元素，例如：

Graphviz 和 mermaid 是两个创建流程和网络图的通用软件。DiagrammeR (Iannone 2022) 包支持用 R 代码生成 Graphviz 或 mermaid 图。可以直接在 RStudio 中打开 Graphviz (.gv) 和 mermaid (.mmd) 文件，如图 2.18 所示。

图 2.18: RStudio 编辑器中的 Graphviz 和 mermaid 图文件

作者也可以直接使用 Graphviz 格式的字符串，如图 2.19 所示。

图 2.19: 用 DiagrammeR 创建 Graphviz 流程图

作者可以在 grViz() 函数中用 @@ 嵌入 R 变量，如图 2.20 所示。

图 2.20: 在 DiagrammeR::grviz 中使用 R 变量的值

除了流程图外，DiagrammeR 还可以创建网络图，如图 2.21 所示。

图 2.21: DiagrammeR 创作的网络可视化图

其他能生成流程图的 R 包包括：nomnoml、diagram、dagitty、ggdadg 和 plantuml 等。

RStudio Desktop 1.4 及以后版本为 R Markdown 文档添加了图形编辑模式。在 RStudio 中打开任意 .Rmd 文件，点击右上方类似 “A” 的按钮 (图 2.22)，可进入可视化编辑器，界面如图 2.23 所示。

图 2.22: R Markdown 编辑模式切换按钮

图 2.23: R Markdown 图形编辑模式

图形化编辑器提供了丰富的菜单栏选项，用于可视化地插入常见文档元素。如图 2.24 所示。

图 2.24: 图形化编辑器提供了很多菜单栏选项

读者可以在 https://rstudio.github.io/visual-markdown-editing/ 了解更多图形化编辑器的知识。